package server.core;

import java.util.concurrent.Callable;

/**
 * The ProblemManager interface defines the functionality that must be
 * implemented in order for a new type of problem to be supported by the
 * server. The methods that are expected to return {@link Callable} objects do
 * so to facilitate utilizing these methods in a manner that allows for prompt
 * interruption as well as running the solver and cache check in parallel.
 * 
 * @author Clayton Edward Taylor
 */
public interface ProblemManager {

	/**
	 * Creates a {@link Callable} object whose call method parses the inputed 
	 * problem data producing a {@link Problem} object as its return result or 
	 * throws an exception if it fails.
	 * 
	 * @param data - The text representation of the problem sent by the client
	 * @return       A Callable object whose call method parses the given data
	 *               and returns a Problem
	 * @see          ProblemManager
	 */
	public Callable<Problem> getProblemParser(String data);
	
	/**
	 * Creates a {@link Callable} object whose call method checks if a solution
	 * for the given {@link Problem} is in the cache for the problem type and
	 * if so returns a {@link Solution} object representing it, otherwise it 
	 * throws an exception.
	 * 
	 * @param p - The object containing a parsed problem
	 * @return    A Callable object whose call method checks the cache and
	 *            returns a Solution if the Problem is present
	 */
	public Callable<Solution> getCacheQuery(Problem p);
	
	/**
	 * Creates a {@link Callable} object whose call method dispatches a solver 
	 * for the given {@link Problem} and upon successful completion it returns
	 * a {@link Solution} object, otherwise it throws an exception.
	 * 
	 * @param p - The object containing a parsed problem
	 * @return    A Callable object whose call method solves the Problem and
	 *            returns a Solution for it
	 * @see       ProblemManager
	 */
	public Callable<Solution> getSolverDispatch(Problem p);
	
	/**
	 * Inserts the {@link Solution} for the given {@link Problem} into the
	 * cache. If there is already a solution associated with the problem then
	 * it is updated.
	 * 
	 * @param p - The object containing a parsed problem
	 * @param s   The object containing a solution to the problem
	 * @see       ProblemManager
	 */
	public void insertCache(Problem p, Solution s);
	
	/**
	 * Clears out the entire contents of the cache.
	 * 
	 * @see ProblemManager
	 */
	public void clearCache();
}
